fix(generator): idempotent install + a consumer re-sync guide - #39

What & why

docs_kit:install was unsafe to re-run: create_initializer clobbered a site's edited config, and add_routes duplicated a route when the site had written it in a different style. Consequence: sites never re-ran it and fossilized on the generator output of the day they were created (the audits found both consumer sites still hand-duplicating render_page and carrying a dead IconHelper).

This makes rails g docs_kit:install fully idempotent — safe on a fresh app AND a years-old site — so re-running it becomes the sanctioned upgrade path as this epic keeps adding routes / initializer lines / AGENTS.md across issues.

Closes #24.

Changes

Design notes

• A flag on the one generator (not a separate docs_kit:update) keeps the guard logic in one place.
• Drift detection stays string-level and conservative — it warns, never auto-edits or deletes site code.
• --sync never re-scaffolds site-owned content (Doc registry, pages, the themed application.tailwind.css); those are the site's.
• SyncReport extracted to its own file (lib/generators/docs_kit/install/sync_report.rb) per the "many small files" rule.

Test coverage (TDD — RED first)

• Route idempotency vs a hand-written, differently-styled routes.rb (single quotes, to:, no .:format): no duplicate root / docs#show / docs_kit/search#index; the site's own syntax is left untouched.
• create_initializer preserves edited config byte-for-byte on re-run + reports the skip/hint.
• --sync scaffolds no site content (registry/pages/CSS) and is idempotent (a second sync duplicates no routes).
• --sync drift detection flags render_page + IconHelper and does not delete them.
• Stimulus: no double-registration when the site already lazy-loads the docs_kit path.

Verification gates

• ✅ bundle exec rspec — 505 examples, 0 failures, 96.57% line coverage (floor is 80%).
• ✅ bundle exec rubocop — clean (103 files).
• ✅ Fresh-app path unchanged — the manifest/route/stimulus specs all still pass (on a fresh app nothing pre-exists, so every step runs as before); docs-kit new still runs the full docs_kit:install.

Live --sync runs (as the issue requires)

1. Against the gem's own docs/ app — a no-op with zero drift warnings ✅

skip  config/initializers/docs_kit.rb exists — compare with <gem>/templates/docs_kit.rb.erb if upgrading
skip  site content (--sync: registry/pages are yours)
identical  route docs#show (already drawn)
identical  route docs_kit/search#index (already drawn)
identical  route root (already drawn)
identical  route docs_kit/llms#index (already drawn)
identical  route docs_kit/llms#full (already drawn)
skip  CSS build (--sync: application.tailwind.css is yours)
identical  app/javascript/controllers/index.js
info  docs-kit synced.

The config initializer diff was empty; a second sync produced zero route changes.

2. Against phlex-reactive/docs — flags render_page + IconHelper ✅

insert  app/controllers/application_controller.rb   (adds `include DocsKit::Controller`)
identical  route docs#show (already drawn)            ← site wrote get 'docs/:doc' => 'docs#show' (single quotes)
identical  route root (already drawn)                 ← site wrote root 'landings#show' (single quotes)
route  get "/docs/search" …                           ← genuinely missing, added
route  get "/llms.txt" … / "/llms-full.txt" …         ← genuinely missing, added
identical  app/javascript/controllers/index.js        ← site lazy-loads docs_kit; NOT double-registered
warn  manual cleanup needed (docs-kit now provides these):
  • app/controllers/application_controller.rb defines its own render_page — delete it; DocsKit::Controller#render_page is included.
  • app/helpers/icon_helper.rb (IconHelper) is dead — docs-kit renders icons via rails_icons (DocsUI::Icon); delete it.

Both drift files were left on disk (warn-only). The consumer's single-quote routes were correctly recognized as already-drawn and not duplicated — the exact bug this issue was about. Its lazy Stimulus registration was preserved, not double-registered (a bug this verification surfaced and this PR also fixes).

Live runs were executed against copies of both apps in a scratchpad; neither real repo was modified.

Out of scope (per the issue)

• Editing the consumer repos (they run --sync themselves).
• Version-aware migrations between docs-kit releases (post-1.0).

https://claude.ai/code/session_01FPQb6z3YwcKRMbvoJhdxnX